Devolução enviada de Pix Webhook
info
📘 Para saber mais sobre webhooks em nossa API, siga o link abaixo:
Quando um pagamento Pix é creditado em sua conta e um reembolso é emitido, a melhor maneira de receber atualizações sobre possíveis erros é por meio do webhook PIX_REFUND_PAYMENT_UPDATED. Se ocorrer um erro durante o processo de reembolso, o status da transação será atualizado e um webhook PIX_REFUND_PAYMENT_UPDATED será acionado.
atenção
Note que este webhook é específico para erros relacionados a reembolsos Pix. Para pagamentos Pix bem-sucedidos — incluindo reembolsos Pix enviados — use PIX_PAYMENT_UPDATED é usado.
Esta é a maneira mais simples de configurar um webhook PIX_REFUND_PAYMENT_UPDATED:
Headers
| Nome | Descrição |
|---|---|
| x-delbank-api-key | Obrigatório. Chave de API |
Corpo da requisição
{
"eventType": "PIX_REFUND_PAYMENT_UPDATED",
"url": "https://example.com.br/webhooks/v1/pixrefundsent", // Add your own URL here
"authorization": "NONE,
"authorizationScheme": "NONE"
}
Aqui está um exemplo de um webhook de um erro em um reembolso Pix enviado:
{
"status": "PIX_ERROR",
"error": {
"code": "DEL20",
"description": "Pix original ainda não foi processado."
},
"eventType": "PIX_REFUND_PAYMENT_ERROR",
"endToEndId": "D38224857202505151236QaPfJMQyyRj",
"idempotencyKey": "E38224857202505151235EU6L6UCKIAM",
"correlationId": null,
"amount": 0.01,
"createdAt": "2025-05-15T12:36:48",
"finishedAt": "2025-05-15T12:36:48",
"description": null,
"payer": null,
"beneficiary": null
}
Aqui estão os atributos que são passados pelo webhook PIX_REFUND_PAYMENT_UPDATED:
| Name | Description |
|---|---|
| status | O status da transação de reembolso PIX. |
| error | Objeto contendo informações sobre o erro |
| error.code | Código interno atribuído ao erro |
| error.description | Descrição do que causou o erro |
| eventType | O tipo de evento que acionou o webhook (ex.: "PIX_REFUND_PAYMENT_EFFECTIVE"). |
| operationType | O tipo de operação que está sendo realizada. |
| endToEndId | O identificador único para a transação de reembolso PIX. |
| originalEndToEndId | O identificador único para a transação PIX original que está sendo reembolsada. |
| idempotencyKey | Uma chave única para garantir a idempotência do processamento do evento. |
| correlationId | O id correlação da transação |
| amount | O valor monetário da transação de reembolso PIX. |
| createdAt | O timestamp indicando quando a transação de reembolso PIX foi criada. |
| description | Uma descrição textual explicando o motivo do reembolso (ex.: "Pedido reembolso"). |
| payer | Um objeto contendo informações sobre o pagador da transação de reembolso PIX. |
| payer.number | O número da conta do pagador. |
| payer.branch | O número da agência da conta do pagador. |
| payer.type | O tipo da conta do pagador (ex.: "CURRENT"). |
| payer.participant | Um objeto contendo informações sobre a instituição financeira do pagador. |
| payer.participant.ispb | O código ISPB da instituição financeira do pagador (ex.: "38224857"). |
| payer.holder | Um objeto contendo informações sobre o titular da conta do pagador. |
| payer.holder.name | O nome do titular da conta do pagador (ex.: "EMPRESA LTDA"). |
| payer.holder.document | O documento do titular da conta do pagador (ex.: "94478450000138"). |
| payer.holder.type | O tipo do titular da conta do pagador (ex.: "LEGAL"). |
| beneficiary | Um objeto contendo informações sobre o beneficiário da transação de reembolso PIX. |
| beneficiary.number | O número da conta do beneficiário. |
| beneficiary.branch | O número da agência da conta do beneficiário. |
| beneficiary.type | O tipo da conta do beneficiário (ex.: "PAYMENT"). |
| beneficiary.participant | Um objeto contendo informações sobre a instituição financeira do beneficiário. |
| beneficiary.participant.ispb | O código ISPB da instituição financeira do beneficiário (ex.: "1111111111"). |
| beneficiary.holder | Um objeto contendo informações sobre o titular da conta do beneficiário. |
| beneficiary.holder.document | O documento do titular da conta do beneficiário (ex.: parcialmente mascarado). |
| beneficiary.holder.type | O tipo do titular da conta do beneficiário (ex.: "NATURAL" ou "LEGAL"). |
| payee | Um objeto contendo informações sobre o recebedor da transação de reembolso PIX. |
| payee.number | O número da conta do recebedor. |
| payee.branch | O número da agência da conta do recebedor. |
| payee.type | O tipo da conta do recebedor (ex.: "PAYMENT"). |
| payee.participant | Um objeto contendo informações sobre a instituição financeira do recebedor. |
| payee.participant.ispb | O código ISPB da instituição financeira do recebedor (ex.: "1111111111"). |
| payee.holder | Um objeto contendo informações sobre o titular da conta do recebedor. |
| payee.holder.document | O documento do titular da conta do recebedor (ex.: parcialmente mascarado). |
| payee.holder.type | O tipo do titular da conta do recebedor (ex.: "NATURAL" ou "LEGAL"). |